Conversation
A reference written by hand beside the code is wrong by the second release, and wrong in the way that costs the most: it looks maintained. So this one is generated, from the declarations the published package carries, and the release builds it from the version it is publishing. typedoc rather than api-documenter, which was the obvious pick: it is the other half of the api-extractor toolchain, api-extractor already runs here for the stability report, and reusing its doc model would have meant one reader of the surface instead of two. It was tried first and it is missing `conn.stream(...)` and `await using`, because both reach the type of a connection through the `declare module` in zudb.d.cts and api-extractor does not follow one. A reference missing the streaming entry point is a reference that sends a reader to the cursor, so the generator that reads the declarations with the TypeScript compiler is the one used here. The same gap is in etc/zudb.api.md, which means the stability gate does not see those two members either. That is a defect in the report rather than in this package, and fixing it means declaring `Connection` some way other than by augmentation, which changes what a consumer's compiler sees. Left alone here and worth its own change. Two checks, because a generated reference fails quietly. Every name `zudb.cjs` exports has to be documented as a value, which catches types that went missing for a name a program can still require, and the two augmented members have to be on the Connection page, which catches the generator quietly becoming one that reads the file and misses them.
An entry point is a glob, and a backslash in a glob escapes whatever follows it. So the path the tool computed for its own sibling arrived at typedoc as `zudb.d.cts` carrying three escapes, matched nothing, and the run produced a reference with nothing in it. Windows only, which is why it passed here and failed there. The checks did their job: fifteen complaints, one per exported name plus the two augmented members, and a red build rather than an empty page in a release artifact. They said it at the wrong altitude though, so an error out of typedoc is now its own failure. A generator that could not find the file it was pointed at has not produced a thin reference, it has produced no reference, and the thirteen missing pages are a true answer to a question nobody asked.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
referenceitem of the client scorecard, for this client: a generated API reference, published with the release rather than written by hand beside it.node tools/reference.mjs <directory>, ornpm run reference, builds every exported name with its signature and what its doc comment says, out of the declarations this package publishes. The release builds the same pages from the version it is about to publish and uploads them, so the reference a release hands over is about that release and not about whatever the tree looked like when somebody last edited a page.Why not api-documenter
It was the obvious pick and it was tried first. api-extractor already runs here for the stability report, so its doc model would have meant one reader of the public surface instead of two, and api-documenter turns that model into markdown with no extra configuration at all.
It is missing
conn.stream(...)andawait using. Both reach the type of a connection through thedeclare moduleblock inzudb.d.cts, and api-extractor does not follow a module augmentation. A reference whoseConnectionpage has nostreamis a reference that sends a reader tocursor, which is the pull underneath it and the thing almost nobody should be holding. So the generator here is typedoc, which reads the declarations with the TypeScript compiler and carries both.Worth saying plainly: the same gap is in
etc/zudb.api.md, so the stability gate does not see those two members either. That is a defect in the report and not in this package, and closing it means declaringConnectionsome way other than by augmentation, which changes what a consumer's compiler sees for a name that is also a value. It is left alone here and it is worth its own change.The two checks
A generated reference fails quietly. It builds, it looks finished, and a reader finds out.
Every name
zudb.cjsexports has to be documented, and documented as a value rather than as a type. That catches the declarations going missing for a name a program can still require, which is the failure this package is shaped to have: the addon and the declarations come out of one Rust crate and are published as two files.The two augmented members have to be on the
Connectionpage. That is the check on the choice of generator: if this ever becomes one that reads the whole file and misses them, it fails here rather than shipping.test/reference.test.mjsruns the tool and reads the page it produced, on every cell of the matrix.